package com.linkgie.galaxyframework.metadata;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 状态字段标注
 * <p>
 * 
 * 用于将实体类型（由 {@link DataEntity} 标注的类型）中的字段标注为状态字段；<br>
 * 被标注的字段的类型必须是单值类型（{@link StandardType#INT}）、（{@link StandardType#TEXT}）、（{@link StandardType#TIMESTAMP}）之一；
 * <p>
 * 
 * 一个实体类型的字段中可以有一个或者多个字段标注 {@link StateKey} ；
 * <p>
 * 
 * 当一个字段标注为 {@link StateKey}
 * 时，该字段的值会作为实体实例的状态值，用于标识该实体的实例处于某种状态，以驱动关注实体实例状态的观察者；
 * <p>
 * 
 * 利用 {@link StateKey} 标注和 {@link StatePredicate} 相关的标注 ，可以建立对实体实例的状态规则；
 * 
 * <br>
 * 
 * 1. 当状态字段设置了状态判定条件时，将状态字段的值作为输入值匹配判定条件，确定最终的状态名； <br>
 * 2. 如果状态字段未设置状态判定条件时，直接以状态字段的值作为状态名；<br>
 * 3. 如果状态字段设置了默认状态{@link #defaultState()}，那么当状态判定条件没有匹配时（返回null），<br>
 * 或未设置状态判定条件且状态字段值为 null 时，采纳默认状态；
 * 
 * @author huanghaiquan
 *
 */
@Target({ ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface StateKey {

	/**
	 * 默认状态；
	 * <p>
	 * 
	 * 如果设置了默认状态时：
	 * <p>
	 * 当状态字段标注了 {@link StatePredicate} 相关的标注（例如 {@link TextState}、
	 * {@link EmptyState} 等）时，如果不匹配其中任何一项状态判定条件时，采纳此属性设置的默认状态；
	 * 
	 * <p>
	 * 当状态字段未标注任何状态判定条件时，如果字段值为 null ，则采纳此属性设置的默认状态；
	 * 
	 * @return
	 */
	String defaultState() default "";

}
